==README for Keywords-Rich-URLs add-on for miniBB==
Release date: August 10, 2009.
Latest update: July 20, 2023.
miniBB version: 3.4+
Author: Paul Puzyrev (minibb.com)

By default, miniBB supports a view of "short" static URLs as described in miniBB manual: 

http://www.minibb.com/forums/manual.html#mod_rewrite

The collection of presented add-ons provide possibility to turn on keyword-rich URLs, which will contain a meaningful phrase based on the topic's and forum's title, so called "SEO-URLs".

What kind pros and cons such approach may bring for your forums? Study the manual below for more information.

Installing keywords-rich URLs depends on very many factors. You must be a SEO- and coding-professional to achieve the exact results, knowing what you would like to achieve. Putting keywords in URLs can't be an automated task for just every website.

This package is for UTF-8 forums only. If you run the forums in the encoding other than UTF-8, the chars replacing script may work improperly. For extending the package, modify the `$replace` array of chars of the `convertTitle` function supplied with each version.

In miniBB, such URLs transformation will take a bit of additional resources, because the parser needs to get the actual phrase and convert it to the new one, which will only contain allowed symbols. On modern and powerful servers this is not a resource-greedy operation however.


==SETUP==

To apply one of the presented packages, do the following:

- choose and copy the desired package to your forums folder

- set $mod_rewrite=TRUE; under miniBB's setup_options.php 

- at the bottom of setup_options.php, put the following strings of code:

if(!defined('REPLACE_PATH')) define('REPLACE_PATH', '/minibb/forums/');
if(!defined('NO_MOD_REWRITE')) include($pathToFiles.'addon_mod_rewrite_#.php');

'REPLACE_PATH' setting is necessary to specify only for the version #3 of this package. If you are going the #1 or #2, just ignore and do not put this line. If required, under this setting, specify the pure path to your forum files as it may appear under $_SERVER['REQUEST_URI'] variable of PHP. This setting will be used in parseRequest...URL() function to get the typed URL of a forum or topic, without leading path.  It's very specific for each server, and you must know how to determine it, and must to put it properly, with the ending slash. If it's set improperly, you may experience a "Redirect loop" when trying to open a forum or a topic.

Under #, there should be specified the number of one of the scripts of this package. For example, 'addon_mod_rewrite_1.php' or 'addon_mod_rewrite_2.php' or 'addon_mod_rewrite_3.php'.

- under .htaccess file, put the rules provided at the top of each package in the comments section.

IMPORTANT: if your forums are set-up in UTF-8 (Unicode), and if some topic's title is posted in Unicode, then the script will try to replace Unicode-chars to their Latin transcription, that way trying to build the most reliable and optimized URL. All modules support conversion of almost any major european Unicode-character. This conversion happens in the `convertTitle` function. Modify this function and its `$replace` array to put additional characters for conversion, if they are not present. Otherwise, if your forum is set up in English only and you don't expect non-English topic titles, you could remove the `$replace` array and the next line following it, this one (It will make the module work faster):

`$topicTitle=str_replace(array_keys($replace), $replace, $topicTitle);`

If the script finds a non-Latin character for conversion, it will be removed from an URL. There is a way to build an URL having Unicode characters present, however this means the customization of any module and .htaccess at more advanced level, and the current free versions of these modules do not support this.

==DESCRIPTION==

Below are some short descriptions of what you will get correctly installing one of the provided add-ons. [FORUM_TITLE] (without parentheses) stands for the forum title which will be put in the URL after conversion, the same for [TOPIC_TITLE]. [FORUM_ID] stands for forum's ID presented in the URL, and [TOPIC_ID] for the topic's ID. [PAGE] means pagination's number, beginning from miniBB 2.4 it's possible to not include the first page's number in the URL, if it may be allowed by the mod_rewrite rules. Pay attention to the syntax of the transformed URLs, there could be quite a lot of combinations and delimiters. Your choice is to put the schema which you like best... there is no absolute SEO-rule regarding this point.


* addon_mod_rewrite_1.php

URL to the forum's first page will look like: [FORUM_TITLE]-f[FORUM_ID].html
URL to the forum's internal page will look like: [FORUM_TITLE]-f[FORUM_ID]-[PAGE].html
URL to the topic's first page will look like: [TOPIC_TITLE]-[FORUM_ID]-[TOPIC_ID].html
URL to the topic's internal page will look like: [TOPIC_TITLE]-[FORUM_ID]-[TOPIC_ID]-[PAGE].html

This is the simplest keyword-rich URLs schema which would work on most installations without buzzing with REPLACE_PATH setting, and it's an extension to the default miniBB's "static-URLs" schema as described in Manual. It just puts forum and topic titles in URLs without paying a lot of attention to their logics, separating words by hyphens. If such URLs repeat the look of static files presented on disk, it would mean they all are collected under one folder, which is rather impossible in efficiency terms; still, it works great for search engines. Most likely it is the most simple yet effective way to go for SEO-newbies.


* addon_mod_rewrite_2.php

URL to the forum's first page will look like: [FORUM_TITLE]-[FORUM_ID]/
URL to the forum's internal page will look like: [FORUM_TITLE]-[FORUM_ID]/index[PAGE].html
URL to the topic's first page will look like: [FORUM_TITLE]-[FORUM_ID]/[TOPIC_TITLE]-[TOPIC_ID].html
URL to the topic's internal page will look like: [FORUM_TITLE]-[FORUM_ID]/[TOPIC_TITLE]-[TOPIC_ID]-[PAGE].html

This is the schema we are using currently for miniBB official forums under http://www.minibb.com/forums/ It follows more "clean" logics of physical files as they would be stored on disk: each forum has its own folder, where paginated listings are put as static 'index' HTML files, and under the same folder, all topics are put as the "HTML" files as well. The first forum page would be 'index.html' which may be ignored by server's directives, and that way it is also done in this schema. Also, in this module it is possible to specify SHORT forum titles for any forum, so they do not take too much space. For example, for our "News and Announcements" forum the keywords-title specified is 'news', for the "Official Addons and Solutions" the keywords-title is 'plugins'. These definitions are put under $specifiedForums array, and in the code you will see how they are taken into attention when loading up the URL for such specified forum. By default, this array is enabled only for www.minibb.com, so you may remove the condition allowing and specifying this array for your own forums.


* addon_mod_rewrite_3.php

URL to the forum's first page will look like: [FORUM_TITLE]-[FORUM_ID]/
URL to the forum's internal page will look like: [FORUM_TITLE]-[FORUM_ID]/[PAGE]/
URL to the topic's first page will look like: [FORUM_TITLE]-[FORUM_ID]/[TOPIC_TITLE]-[TOPIC_ID]/
URL to the topic's internal page will look like: [FORUM_TITLE]-[FORUM_ID]/[TOPIC_TITLE]-[TOPIC_ID]/[PAGE]/

This is even more advanced URLs schema, which follows some physical files and folders logics as well. If there would be files presented on disk, it means each forum has its own folder, and it has subfolders for paginated indexes, or subfolders for certain topics under this forum, which have paginated indexes as subfolders as well. In the mod_rewrite rules, there are also some extra rules which redirect to the proper URL if there has been not typed an ending slash. Both topic and forum titles are present in such schema, which is specially important for categorized forums. IMPORTANT: having such schema, you must set $cookiepath setting of setup_options.php having an exact value (not an empty one like ''). In most common cases, set it to '/' meaning the whole root folder of your website. If you set it to empty default value, some forum operations like deletion may not work, because CSRF protection cookie may be set to the virtual non-existing path.


==PROGRAMMERS GUIDE==

In all of the described add-ons, forum and topic titles are converted using the function called "convertTitle". This function does the following:

- removes everything which is not alphanumerical or a dot
- remove any HTML-entities
- removes dots if there are more than 2 dots presented in the phrase
- removes some unmeaningful keywords like words 'and', 'or', 'in', 'a' etc.
- cuts the topic's keywords if there are more than 70 characters present
- performs some other cleaning operations on the final phrase
- if in the final the topic's title becomes empty or too short, it just returns the word 'topic'
- the returned phrase comes in lowercase only.


You may edit this function's output on your own wish, or quote our team's services to make it more better for your forums. For example, instead of the hyphen as delimiter between words, it's possible to put underscore ('_') or plus sign ('+'); it's also possible to make it case-sensitive, despite it doesn't matter a lot for a search engine. There are tons of ways to make it regarding your own point of view. If you have met some other rules which need to be added to that function, let us know! It's impossible to know about each and every possible case. Also, you are always welcome to suggest new schemas, miniBB is not limited by anything in this aspect.


There are used the following functions, which in provided add-ons override the default ones:

* addForumURLPage($full_url, $currPageNum)

- the function adds page number ($currPageNum) to the forum URL ($full_url) which is earlier built with the function genForumURL(). Depending on page number and URLs schema, here it's possible to skip the first page's number in the URL.

* addTopicURLPage($full_url, $currPageNum)

- the same as above, but for the topic's URL.

* genForumURL($main_url, $forum_id, $forum_name)

- the function generates and returns an URL for the certain forum, getting its title ($forum_name) and forum ID ($forum_id). This is a "clear" URL without pagination ending, which is also used in pageNav function of miniBB. In all cases, it's impossible to tie up the forum's URL based on mod_rewrite condition without putting its ID in the URL, so this is a mandatory number.

* genTopicURL($main_url, $forum_id, $forum_name, $topic_id, $topicTitle)

- the same as above, the function generates a "clear" URL for the certain topic, getting its title ($topicTitle), topic ID ($topic_id), as well as forum's title and ID where this topic is present. It only depends on URLs schema, if forum's title information needs to be included here; but it is mandatory for forum ID.

* parseRequestForumURL($main_url)

- the function returns the current forum URL as it is typed in the browser. In most cases, there should be some manipulation with $_SERVER['REQUEST_URI'], stripping off the forum's folder name or doing something else. In result, we should get the complete forum-URL request. This is very important for redirection issues: if you forum title has been changed, or if has been typed wrong, the script should take the visitor to the only valid URL. 301 "move permanently" header will be used for that case. By default, this function just splits the $_SERVER['REQUEST_URI'] by slash symbol, and returns the last value of the splitting array. However it would work only for the URL schemas which do not put slashes in topic and forum URLs (for example, pagination is added using the hyphen). It becomes very specific to the certain website's structure, if slashes are used in converted URLs.

* parseRequestTopicURL($main_url)

- the same as described above, but works for the topic's URL redirection.


==NOTES==

It doesn't really matter which URLs schema you choose, or how your forums URLs will look like. The most important thing is QUALITY and AUDIENCE of your forums. In SEO, it's important how many other websites refer to your forums, so whatever you should take care of, is not the look of the URLs, but the forums content itself, and their promotion. However, if you would like to achieve great SEO results, such special schemas are not the unwanted thing. Best of luck! :-)


==FINALLY==
Questions? Suggestions? Improvements? Post them quickly on our support forums:
http://www.minibb.com/forums/
