phpMyFAQ 3.1 Documentation

Contents

  1. Introduction
    1. License
    2. Support
    3. Copyright
  2. Installation
    1. Requirements
    2. Preparations
    3. Setup
    4. First Steps
    5. Notes regarding the search-function
    6. Automatic content negotiation
    7. PHP settings
    8. Enabling support for SEO-friendly URLs
    9. Enabling LDAP support
    10. PDF export
    11. Static solution ID
    12. Spam protection
    13. Attachments
    14. Twitter
    15. Server side recommendations
    16. Syntax Highlighting
    17. Elasticsearch Support
  3. Upgrading
    1. Upgrading from phpMyFAQ 2.9.x
    2. Upgrading from phpMyFAQ 3.0.x
    3. Upgrading phpMyFAQ 3.1.x versions
    4. Modifying templates for phpMyFAQ 3.1.x
  4. Frontend
    1. Change languages
    2. Advanced search
    3. Instant Response
    4. Add FAQ
    5. Add questions
    6. Open questions
    7. Submit translation
    8. Social networks
    9. Internal references
    10. Public user registration
    11. Complete secured FAQ
  5. Administration
    1. User Administration
    2. Group Administration
    3. Section Administration
    4. Category Administration
    5. Record Administration
    6. Comment Administration
    7. Glossary
    8. News Administration
    9. Attachment Administration
    10. Statistics
    11. Exports
    12. Backup
    13. Configuration
    14. Multisite Configuration
    15. Template Meta data
  6. Customizing phpMyFAQ
    1. HTML Structure
    2. Layout
    3. More Templates
  7. Customizing phpMyFAQ
    1. Creating custom layout
  8. Developer documentation
    1. [phpMyFAQ development][91]
    2. rest/json API
    3. DEBUG Mode
  9. One more thing

1. Introduction

phpMyFAQ is a multilingual, completely database-driven FAQ system. It supports various databases to store all data, PHP 7.4+ is needed in order to access this data. phpMyFAQ also offers a multi-language Content Management System with a WYSIWYG editor and an Image Manager, real time search support with Elasticsearch, flexible multi-user support with user, group and section based permissions on categories and records, a wiki-like revision feature, a news system, user-tracking, 40+ supported languages, enhanced automatic content negotiation, HTML5/CSS3 based responsive templates with support for own text and HTML snippets, PDF-support, a backup-system, a dynamic sitemap, related FAQs, tagging, built-in spam protection systems, OpenLDAP and Microsoft Active Directory support, and an easy-to-use installation script. You can run phpMyFAQ on almost every web hosting provider or in the cloud in a Docker container.

This documentation should help you with installing, administrating and using phpMyFAQ.

back to top


1.1. License

phpMyFAQ is published under the Mozilla Public License Version 2.0 (MPL). This license guarantees you the free usage of phpMyFAQ, access to the source code and the right to modify and distribute phpMyFAQ.

The only restrictions apply to the copyright, which remains at all times at Thorsten Rinne and the phpMyFAQ Team. Any modified versions of phpMyFAQ will also fall under the terms of MPL. Any other program, that may only be accessing certain functions of phpMyFAQ is not affected by these restrictions and may be distributed under any type of license.

A commercial usage or commercially distribution of phpMyFAQ, e.g. on CD-ROMs, is allowed, as long as the conditions mentioned above are met.

We decided to use MPL as the licensing model for phpMyFAQ because we feel that it is a good compromise between the protection of the openness and free distribution on the one hand and the interaction with other software regardless of its licensing model. When compared to other licensing models its text is short and easily comprehensible, even for newcomers.

This documentation is licensed under a Creative Commons License.

back to top


1.2. Support

If you should run into any problems using phpMyFAQ check out our support forums at forum.phpmyfaq.de. You can also use our Twitter account @phpMyFAQ to ask us short question if they fit into 280 characters. There is no free support by phone or email, please refrain from calling or mailing us.

The phpMyFAQ team offers the following paid services:

  • Customizing
  • Support

If you're interested, just take a look at our support page.

back to top


© 2001-2022 by Thorsten Rinne and phpMyFAQ Team under the Mozilla Public License 2.0. All rights reserved.

back to top


2. Installation

2.1. Requirements for phpMyFAQ

phpMyFAQ addresses a database system via PHP. In order to install it locally you will need a web server that meets the following requirements:

  • PHP
    • from version 7.4+ or PHP 8
    • memory_limit = 128M (the more the better)
    • cURL support
    • GD support
    • XMLWriter support
    • JSON support
    • Filter support
    • SPL support
    • FileInfo support
  • Web server ( Apache 2.x or nginx 1.0+
  • Database server
  • Search engines (optional)
  • correctly set: access permissions, owner, group
  • Docker (optional)

You can only run phpMyFAQ successfully with constraints affect the directives open_basedir and disable_functions, which can be set in the central php.ini or the httpd.conf respectively.

In case PHP runs as module of the Apache, you will have to be able to do a chown on the files before installation. The files and directories must be owned by the web server's user.

You can determine which versions your web server is running by creating a file called info.php with the following content: <?php phpinfo(); ?>

Upload this file to your webspace and open it using your browser. The installation-script checks which version of PHP is installed on your server. Should you not meet the requirements, you cannot start the installation process.

In case you're running PHP before 7.3 you cannot use phpMyFAQ.

phpMyFAQ uses a modern HTML5/CSS3 powered markup. The supported browsers are the latest Mozilla Firefox (Windows/macOS/Linux), the latest Safari (macOS/iOS), the latest Chrome (Windows/macOS/Linux), the latest Opera (Windows/macOS/Linux) and Microsoft Edge (Windows/macOS/Linux).

We recommend to use always the latest version of Firefox, Chrome, Safari, Opera or Microsoft Edge.

back to top


2.2. Preparations

2.2.1. Classic Shared Web Hosting

You can install phpMyFAQ via one of the provided packages as .zip or .tar.gz or using Git. If you choose our package, download it and unzip the archive on your hard disk.

If you want to use Git, please run the following commands on your shell:

$ git clone git@github.com:thorsten/phpMyFAQ.git 3.1
$ cd phpMyFAQ
$ curl -s https://getcomposer.org/installer | php
$ php composer.phar install
$ curl -o- -L https://yarnpkg.com/install.sh | bash
$ yarn install
$ yarn build

You can modify the layout of phpMyFAQ using templates. A description of how this is done can be found below. Copy all unzipped files to your web server in a directory using FTP. A good choice would be the directory faq/. Important: Writing permission for your script is needed in this directory to be able to write the file config/database.php during installation. This is the case if you're running PHP as CGI or as mod_php with disabled safe-mode. The installation script will stop when your web server isn't configured as needed.

It might help to set chmod 775 to the whole phpMyFAQ directory to avoid problems during the installation. If you're running a very restrictive mod_php installation you should keep the chmod 775 for the following files and directories even after the successful installation:

  • the directory attachments/
  • the directory config/
  • the directory data/
  • the directory images/

All other directories shouldn't be world-writable for your own security.

Note: If you're running SELinux, you may need further configuration or you should disable it at all.

The database user needs the permissions for CREATE, DROP, ALTER, INDEX, INSERT, UPDATE, DELETE and SELECT on all tables in the database.

2.2.2. Cloud Hosting via Docker

You first need a database, let's try with a MariaDB container:

$ docker run -ti -n phpmyfaq-db mariadb

Then start the phpMyFAQ web application:

$ docker run -ti --link phpmyfaq-db:db -p 8080:80 phpmyfaq/phpmyfaq

back to top


2.3. Setup

Open your browser and type in the following URL:

http://www.example.com/faq/setup/index.php

Substitute www.example.com with your actual domain name. When the site is loaded enter the address of your database server (e.g. db.provider.com), the database port, your database username and password as well as the database name. The database have to be created with UTF-8 character set before running the installation script. You can leave the prefix-field empty. If you are planning on using multiple FAQs in one database you will have to use a table prefix, though (i.e. sport for a sports FAQ, weather for a weather FAQ, etc.). Please note that only letters and an underline: "_" can be used as the prefix.

If your PHP was compiled with the LDAP extension you can add your LDAP information, too. Then you can to insert your LDAP information as well.

When using multiple FAQs you need to install them independently into different directories (e.g. faq1/, faq2/. faq3/ etc.). In addition you can enter your language, default here is English. Furthermore you should register your name, your email address and - very importantly - your password. You must enter the password twice and it have to be at least six characters long. Then click the button "install" to initialize the tables in your database.

back to top


2.4. First Steps

You can enter the public area of your FAQ by entering

http://www.example.com/faq/index.php

into your browser's address field. Your FAQ will be empty and presented in the the standard layout.

To configure phpMyFAQ point your browser to

http://www.example.com/faq/admin/index.php

Use the username admin and your selected password for your first login into the admin section.

Some variables that does not change regularly, they can be edited in the file config/constants.php. You can change the

  • the time zone of your server (default: "Europe/Berlin")
  • the timeout in the admin section (default: 30 minutes)
  • the timeout warning pop-up in the admin section (default: 5 minutes)
  • the solution id start value (default: 1000)
  • the incremental value of the solution id (default: 1)
  • the number of records in the Top10 (default: 10)
  • the number of the latest records (default: 5)
  • flag with which Google site map will be forced to use the current PMF SEO URL schema (default: true)
  • the number with which the Tags Cloud list is limited to (default: 50)
  • the number with which the autocomplete list is limited to (default: 20)

back to top


2.5. Notes regarding the search functionality

  • The boolean full-text search will only work with MySQL and if there are some entries in the database (5 or more). The term you are looking for should also not be in more than 50% of all your entries, or it will automatically be excluded from search. This is not a bug, but rather a feature of MySQL.
  • The search on other databases are using currently the LIKE operator.
  • To improve the search functionality you can use Elasticsearch support as well, please check this documentation.

back to top


2.6. Automatic content negotiation

To set the default language in your browser you have to set a variable that gets passed to the web server. How this is done depends on the browser you are using.

  • Mozilla Firefox

    Tools -> Options -> Content -> Languages

  • Google Chrome / Microsoft Edge / Opera

    Settings -> Details -> Language settings

  • Safari

Safari uses the macOS system preferences to determine your preferred language:

`System preferences -> International -> Language`

back to top


2.7. PHP settings

  • We recommend using a PHP accelerator or OpCode cache like APC
  • Allocate at least 128 MB of memory to each PHP process
  • Required extensions: GD, JSON, Session, MBString, Filter, XMLWriter, SPL, FileInfo
  • Recommended configuration:

      memory_limit = 128M
      file_upload = on

back to top


2.8. Enabling support for SEO-friendly URLs

Apache Web server

If you want to enable the search engine optimization you have to activate the mod_rewrite support in the admin backend in the configuration page. You also have to edit the path information for the "RewriteBase". If you installed phpMyFAQ on root directory "/" you should set in RewriteBase / Please check, if AllowOverride All is set correctly in your httpd.conf file so that the .htaccess rules work.

nginx Web server

If you want to enable the search engine optimization you have to copy the rewrite rules in the file nginx.conf to your nginx.conf. Then you have to activate the URL rewrite support in the admin backend in the configuration page.

IIS Web server

If you want to enable the search engine optimization you have to activate the URL rewrite support in the admin backend in the configuration page.

back to top


2.9. Enabling LDAP support

If you're entered the correct LDAP information during the installation you have to enable the LDAP support in the configuration in the admin backend. Now your user can authenticate themselves in phpMyFAQ against your LDAP server or even an Microsoft Active Directory.

If you need special options for your LDAP or ADS configuration you can change the LDAP configuration in the admin configuration panel.

If you want to add LDAP support later, you can use the file config/ldap.php.original as template and if you rename it to config/ldap.php you can use the LDAP features as well after you enabled it in the administration backend.

back to top


2.10. PDF export

Main features of the PDF export:

  • supports all ISO page formats;
  • supports custom page formats, margins and units of measure;
  • supports UTF-8 Unicode and Right-To-Left languages;
  • supports TrueTypeUnicode, OpenTypeUnicode, TrueType, OpenType, Type1 and CID-0 fonts;
  • includes methods to publish some HTML code;
  • includes graphic (geometric) and transformation methods;
  • includes methods to set Bookmarks and print a Table of Content;
  • supports automatic page break;
  • supports automatic page numbering and page groups;
  • supports automatic line break and text justification;
  • supports JPEG and PNG images natively, all images supported by GD (GD, GD2, GD2PART, GIF, JPEG, PNG, BMP, XBM, XPM)

back to top


2.11. Static solution ID

phpMyFAQ features a static solution ID which never changes. This ID is visible next to the question on a FAQ record page. You may think why do you need such an ID? If you have a record ID 1042 it is now possible to enter only the ID 1042 in the input field of the full-text search box, and you'll be automatically redirected to the FAQ record with the ID 1042. By default, the numbers start at ID 1000, but you can change this value in the file inc/constants.php. You can also change the value of the incrementation of the static IDs.

back to top


2.12. Spam protection**

phpMyFAQ performs these three checks on public forms:

  1. Check against IPv4 and IPv6 Network address
  2. Check against banned words
  3. Check against the captcha code

The IPv4 and IPv6 Network addresses can be added or removed in the configuration panel in the administration backend. If you want to add banned words to phpMyFAQ, then you have to edit the file src/blockedwords.txt. Please add only one word per line.

back to top


2.13. Attachments**

phpMyFAQ supports encrypted attachments. The encryption uses the AES algorithm implemented in mcrypt extension (if available) or with native PHP Rijndael implementation. The key size vary depending on implementation used and can be max 256 bits long. Use of mcrypt extension is strongly recommended because of performance reasons, its availability is checked automatically at the run time.

Please be aware:

  • Disabling encryption will cause all files be saved unencrypted. In this case you'll benefit sparing disk space, because identical files will be saved only once.
  • Do not change the default attachment encryption key once files was uploaded. Doing so will cause all the previously uploaded files to be wrong decrypted. If you need to change the default key, you will have to re-upload all files.
  • Always memorize your encryption keys. There is no way to decrypt files without a correct key.
  • Files are always saved with names based on a virtual hash generated from several tokens (just like key and issue id etc), so there is no way to asses a file directly using the name it was uploaded under.
  • Download continuation isn't (yet?) supported.

back to top


2.14. Twitter support**

phpMyFAQ supports Twitter via OAuth. If you enable Twitter support in the social network configuration and add phpMyFAQ as a Twitter application on twitter.com, all new FAQ additions in the administration backend will also post the question of the FAQ, the URL of the FAQ and all tags as hashtags to Twitter, e.g. the tag "phpMyFAQ" will be converted to "#phpmyfaq".

back to top


2.15 Server side recommendations**

MySQL / Percona Server / MariaDB

interactive_timeout = 120
wait_timeout = 120
max_allowed_packet = 64M

back to top


2.16 Syntax Highlighting**

The bundled highlight.js syntax highlighting component will find and highlight code inside of <pre><code> tags; it tries to detect the language automatically. If automatic detection doesn't work for you, you can specify the language in the class attribute:

<pre><code class="html">...</code></pre>

The list of supported language classes is available in the class reference. Classes can also be prefixed with either language- or lang-.

To disable highlighting altogether use the "nohighlight" class:

<pre><code class="nohighlight">...</code></pre>

back to top


2.17 Elasticsearch Support**

To improve the search performance and quality of search results it's possible to use Elasticsearch 5.x. You need a running Elasticsearch 5.x installation accessible by phpMyFAQ via HTTP/REST. You can add the IP(s)/Domain(s) and port(s) of your Elasticsearch cluster during installation or later by renaming the Elasticsearch file located in the folder config/. If you choose to add this during installation, the file will be automatically written and the index will be built.

back to top


3. Upgrading

First, please download the latest package of phpMyFAQ. Upgrading to phpMyFAQ 3.1.x is possible from the following versions:

  • phpMyFAQ 2.9.x
  • phpMyFAQ 3.0.x
  • phpMyFAQ 3.1.x

If you're running an older version of phpMyFAQ we recommend a new and fresh installation. If you need support for updating an old FAQ from the 1.x, 2.0.x, 2.5.x, 2.6.x, 2.7.x or 2.8.x series, please send us an [e-mail][68].

back to top


3.1. Upgrading from phpMyFAQ 2.9.x

Upgrading from 2.9.x is a major upgrade. Please make a full backup before you run the upgrade! First you have to delete all files except:

  • database.php and ldap.php (if you use LDAP) in the directory config/
  • all files in the directory assets/template/
  • the directory attachments/
  • the directory data/
  • the directory images/

Download the latest phpMyFAQ package and copy the contents into your existing FAQ directory, the open the following URL in your browser:

http://www.example.com/faq/setup/update.php

Choose your installed phpMyFAQ version and click the button of the update script, your version will automatically be updated.

You have to move your template files to the directory assets/template/. The default layout is be stored in the folder assets/template/default/.

back to top


3.2. Upgrading from phpMyFAQ 3.0.x

Upgrading from 3.0.x is a major upgrade. Please make a full backup before you run the upgrade! First you have to delete all files except:

  • in the directory config/
    • keep the file database.php
    • only if using LDAP/ActiveDirectory support also keep the file ldap.php
  • in the directory assets/template/
    • keep all files
  • the directory attachments/
  • the directory data/
  • the directory images/

Download the latest phpMyFAQ package and copy the contents into your existing FAQ directory, the open the following URL in your browser:

http://www.example.com/faq/setup/update.php

Choose your installed phpMyFAQ version and click the button of the update script, your version will automatically be updated.

You have to move your template files to the directory assets/template/. The default layout is be stored in the folder assets/template/default/.

back to top


3.3. Upgrading phpMyFAQ 3.1.x

Updating an existing phpMyFAQ 3.1.x installation is fairly simple. First you have to delete all files except:

  • all files in the directory config/
  • all files in the directory assets/themes/
  • the directory attachments/
  • the directory data/
  • the directory images/

Download the latest phpMyFAQ package and copy the contents into your existing FAQ directory, the open the following URL in your browser:

http://www.example.com/faq/setup/update.php

Choose your installed phpMyFAQ version and click the button of the update script, your version will automatically be updated.

back to top


3.5. Modifying templates for phpMyFAQ 3.1.x

We recommend you'll take a look at the main Bootstrap documentation. Please don't forget that the style sheets are written with SCSS. You have to compile the SCSS files into CSS using a SCSS compiler with Node.js.

If you need help with theming phpMyFAQ please don't hesitate to ask in our forum. We will also release new themes from time to time on our homepage and release them as open source on our Github page.

Note: The character set for all languages and templates is UTF-8. If you notice problems with e.g. German umlauts you have to convert your templates to UTF-8 encoding. Please use UNIX file endings \n instead of Windows file endings with \r\n.

back to top


4. Frontend

The public phpMyFAQ frontend has a simple, HTML5/CCS3 based default layout based on Bootstrap v4. The header has the main links for the all categories, instant response, add FAQs, add questions, open questions, sitemap and contact. On the left side you only see the main categories. You can also change the current language at the bottom of the FAQ, use the global search in the center of the FAQ or use the login box in the upper right if you have a valid user account. On the right side you see a list of the most popular FAQ records, the latest records, and the sticky FAQ records. On the pages with the FAQ records you'll see the other records of the current category and the tag cloud if you're using tagging.

back to top


4.1. Change languages

As written above there's a select box for changing the current language. If you're visiting a phpMyFAQ powered FAQ, the current language will be the one you're browser is using or the language which was selected by the administrator of the FAQ. If you change the language you'll see the categories and records of your chosen language. If there are no entries in this language you'll see no entries. If you're switching to languages with right to left text direction (for example Arabic, Hebrew or Farsi) the whole default layout will be switching according to the text direction.

Note: phpMyFAQ uses a WYSIWYG online editor that has support for multiple languages. However, phpMyFAQ comes only with English language pack installed so changing the current language will not change the language of WYSIWYG editor. If you would like to have WYSIWYG editor in another language, just download the latest language pack, extract it and upload the extracted files to admin/editor directory under your phpMyFAQ's installation directory on your web server.

back to top


4.3. Advanced search

On the page with the advanced search you have more possibilities to find an entry. You can search over all language if you want to. It's also possible to search only in one selected category.

back to top


4.4. Instant Response

The Instant Response is directly built into the main search bar in the top of the FAQ with direct access to the whole FAQ database and the page will return results while you're typing into the input form. For performance reasons only the first 10 results will be suggested.

back to top


4.5. Add FAQ

On the Add FAQ page it's possible for all users to add a new FAQ record. The users have to add a FAQ question, select a category, add an answer, and they have to insert their name and e-mail address. If the spam protection is enabled they have to enter the correct captcha code, too. New FAQ entries won't be displayed and have to be activated by an administrator.

If an user is logged in, the name and e-mail address are filled automatically.

back to top


4.6. Add questions

On the Add question page it's possible for all users to add a new question without an answer. If the question is submitted, phpMyFAQ checks the words for the question and will do a full text search on the database with the existing FAQs. If we found some matches the user will get some recommendations depending on the question he submitted.

The users have to add a question, select a category, and they have to insert their name and e-mail address. If the spam protection is enabled they have to enter the correct captcha code, too. By default new questions won't be displayed and have to be activated by an administrator.

If an user is logged in, the name and e-mail address are filled automatically.

back to top


4.7. Open questions

This page displays all open questions and it's possible for all users to add an answer for this question. The user will be directed to the add FAQ page. If the spam protection is enabled they have to enter the correct captcha code, too.

back to top


4.8. Submit translation

On every FAQ record page there's a select box for languages and a button to translate an existing FAQ record to another language. The translating user will be directed to a special add content page with the original entry and a stripped down WYSIWYG editor component. If the spam protection is enabled they have to enter the correct captcha code, too.

If an user is logged in, the name and e-mail address are filled automatically.

Note: Please do not forget to add also a translated category, otherwise you won't be able to activate the translated entry.

back to top


4.9. Social networks

On every FAQ page there are a direct links to various social networks to share the current FAQ page. The supported social networks are:

You can disable the support for social networks completely in the administration backend.

back to top


4.10. Internal references

For better usability there are some helpful links below every FAQ record. If the administrator added tags to the records they will be displayed next to five (or more) related articles. The related articles are based on the content of the current FAQ entry. On the right side you'll see links to all entries of the current category and the complete tag cloud of the whole FAQ.

back to top


4.11. Public user registration

On the upper right border of the default layout the users of the FAQ also have the possibility to register themselves. The user generated accounts are unactivated by default and the administrator has to activate them.

back to top


4.12. Complete secured FAQ

If enabled by the administrator a phpMyFAQ installation can be completely secured. This means all content is only available after a successful login. To avoid crawled content on search engines you should change the meta tags in index.html file from INDEX, FOLLOW to NOINDEX, NOFOLLOW.

back to top


5. Administration

The administration of phpMyFAQ is completely browser-based. The admin area can be found under this URL:

http://www.example.com/faq/admin/index.php

You can also login in the public frontend and after the successful login you'll see a link to administration backend, too.

If you have lost your password you can reset it. A new random password will be generated and sent to you via e-mail. Please change it after your successful login with the generated password.

After entering your username and password you can log into the system. On the start page you can see the administration menu on the top, some statistics about visits, entries, news and comments in the middle of the page. At the bottom of the main admin page you'll see a button for version information. If you click on that button your version of phpMyFAQ will check the latest version number from our website phpmyfaq.de. We do not log anything in this process! A second button is our online verification service. Then clicking on the button phpMyFAQ calculates a SHA-1 hash for all files and checks it against a web service provided on phpmyfaq.de. With this service it's possible to see if someone changed files.

You can switch the current language in the administration backend and you have an info box about the session timeout.

back to top


5.1. User Administration

phpMyFAQ offers a flexible management of privileges (or rights) for different users in the admin area. To search for a certain user just start typing the username in the input form and you'll get a list of hits for usernames. It is possible to assign different privileges to real people (represented by the term users). Those privileges are very detailed and specific, so that you could allow a certain user to edit but not to delete an entry. It is very important to contemplate which user shall get which privileges. You could edit an entry by completely deleting all content, which would be equivalent to deleting the whole entry. The number of possible users is not limited by phpMyFAQ.

Keep in mind that new users have no privileges at all, you will have to assign them by editing the user's profile.

A user without any permission in the admin section can still gets read access to categories and records. You can set the permissions on categories and records in the category and record administration frontend.

back to top


5.2. Group Administration

phpMyFAQ also offers a flexible management of privileges (or rights) for different groups in the admin area. You can set permissions for groups in the same way like for users described in the topic above.

Please note that the permissions for a group are higher rated than the permissions on a user. To enable the group permissions, please set the permission level from basic to medium in the main configuration.

back to top


5.3. Section Administration

Sections in phpMyFAQ are a little bit special. You can define sections for large FAQ installation to separate content not only between different groups but even for section. A section could be a part of a big corporate company.

back to top


5.4. Category Administration

phpMyFAQ lets you create different categories and nested sub-categories for your FAQs. You can also re-arrange your categories in a different order. It is possible to use various languages per category, too; there's also a frontend to view all translated categories. For accessibility reasons you should add a small description for every category. You can add an image for every category, which will be shown even on the start page, if you flag this category with this configuration. If you add a new category, you can set the permissions for users and groups, and you can bind an administrator to that category. This is quite nice if you want to share the work in your FAQ between various admin users.

back to top


5.5. FAQ Administration

You can create entries directly in the admin area. Created entries are NOT published by default. All available FAQs are listed on the page "Edit FAQs". By clicking on them the same interface that lets you create records will open up, this time with all the relevant data of the specific entry. The meaning of the fields is as follows:

  • Category

    The place in the FAQ hierarchy where this entry will be published depends on these settings. You can choose one or more categories where to store the entry. If you want to add a FAQ record to more than one category you have to

    select the categories with your mouse and press the CTRL key.

  • Question

    This is the question or headline of your entry.

  • Answer

    The content is an answer to the question or a solution for a problem. The content can be edited with the included WYSIWYG (What You See Is What You Get) editor when JavaScript is enabled. You can place images where you want with the integrated image manager. The Editor can be disabled in the configuration if you want.

  • Language

    You can select the language of your FAQ. By default the selected language saved in the configuration will be chosen. You can create entries in multiple languages like this: Write an article in English (or any other language) and save it. Now choose Edit FAQs and edit your English FAQ record. Change the question, answer and keywords and change language to, let's say Brazilian Portuguese. Save the FAQ record. Now you can, when you click edit records, see both FAQs in your list, having the same id, yet different languages.

  • Attachments

    You can add attachments like PDFs or any other binary data using the Add attachment button. If you click on the button, a popup opens and you can upload an attachment. Please keep in mind that the PHP configuration about upload size will be checked.

  • Keywords

    Keywords are relevant for searching through the database. In case you didn't include a specific word in the FAQ itself, but it is closely related to the content you may wish to include it as a keyword, so the FAQ will come up as a search result. It is also possible to use non-related keywords so that a wrongly entered search will also lead to the right results.

  • Tags

    You can add some tags about the current FAQ here. An Ajax-based auto-completion method helps you while typing your tags.

  • Author

    It is possible to specify an author for your FAQ.

  • Email

    It is possible to specify the author's email for your FAQ, but the email address won't be shown in the frontend.

  • Solution ID

    Every FAQ generates automatically a so-called solution ID. All records can be accessed directly by putting this ID into the search box.

  • Active?

    If a FAQ is "active" it is visible in the public area and will be included in searches. Is it "deactivated" it will be invisible. Suggested FAQs are deactivated by default to prevent any abuse.

  • Sticky?

    If a FAQ is "sticky" it is a very important FAQ record and will be shown always on all pages on the right column. You should mark records as sticky if they are very important for your whole FAQ. Sticky records also appear at the top positions of the lists of FAQ entries.

  • Comments?

    If you do not want to allow public comments for this FAQ you can disable the feature here.

  • Revision

    Like a wiki, phpMyFAQ supports revisions of every entry. New revisions won't be created automatically but you can create a new one if you click on "yes". The old revision will be stored in the database and the new current revision will be displayed in the public frontend. You can also bring back old revisions into the frontend if you select an old revision and save them as a new one.

  • Date

    You have three options for the FAQ creation date. You can choose to refresh the date of the FAQ entry for every update, or you can keep the date, or you can set an individual date for the FAQ entry.

  • Permissions

    If you add or edit a new entry, you can set the permissions for users and groups. Please note that the permissions of the chosen category override the permissions of the FAQ itself.

  • Record expiration time window

    If you need to you can set a time frame from one date to a second date when the FAQ entry should be valid and visible. Before and after this time frame the entry isn't visible and cannot be accessed.

  • Date

    Date of the last change.

  • Changed?

    This field is reserved for comments that can reflect what changes have been applied to a certain entry. This helps multiple admins to keep track of what happened to the entry over time. Any information entered here will remain invisible in the public area.

  • Changelog

    The changelog lists all previous changes, including user and date of change.

You can edit and delete all records as well. Please note that old revisions won't be deleted until the whole FAQ is deleted.

phpMyFAQ lets visitors contribute to the FAQ by asking questions. Every visitor is able to view these open questions in the public area, and may give an answer. If you wish to get rid of open questions you can do so using this section. Alternatively you can take over a question and answer it yourself and hereby add it to the FAQ.

back to top


5.6. Comment Administration

In this straight frontend you can see all comments that have been posted in the FAQs and the news. You cannot edit comments but you can delete them with one easy click.

back to top


5.7. Glossary

A glossary is a list of terms in a particular domain of knowledge with the definitions for those terms. You can add, edit and delete glossary items here. The items will be automatically displayed in tags in the frontend.

back to top


5.8. News Administration

phpMyFAQ offers the ability to post news on the starting page of your FAQ. In the administration area you can create new items, edit existing news or delete them.

back to top


5.9. Attachment Administration

In the attachment administration you can see an overview of all all attachments with their filename, file size, language and MIME type. You can delete them, too.

back to top


5.10. Statistics

Below every entry visitors have the chance to rate the overall quality of a FAQ by giving ratings from 1 to 5 (whereas 1 is the worst, 5 the best rating). In the statistics the average rating and number of votes becomes visible for every rated entry. To give you a quick overview entries with an average rating of 2 or worse are displayed in red, an average above 4 results in a green number.

View Sessions This functions lets you keep track of your visitors. Every visitor is assigned an ID when coming to your starting page, that identifies him during his whole visit. Using the information gathered here you could reconstruct the way visitors use your FAQ and make necessary adjustments to your categories, content or keywords.

View Adminlog The adminlog allows you to track any actions taken by users in the admin area of phpMyFAQ. If you feel you have an intruder in the system you can find out for sure by checking the admin log.

Search statistics On the search statistics page you'll get a report about which keywords and how often your users are searching. This information is split into keywords, the number of searches for this term, the language and the overall percentage.

Reports On the reports page you can select various data columns to generate a report about content and usage of your FAQ installation. You can export the report then a CSV file.

back to top


5.11. Exports

You can export your contents of your whole FAQ or just some selected categories into four formats:

  • a JSON file
  • a plain HTML5 file
  • a PDF file with a table of contents

back to top


5.12. Backup

Using the backup function it is possible to create a copy of the database to a single file. This makes it possible to restore the FAQ after a possible "crash" or to move the FAQ from one server to another. It is recommended to make regular backups of your FAQ.

  • backup data A backup of all data will include all entries, users, comments, etc.
  • backup logs The sessions of visits and the adminlog will be saved (i.e. all log files). This information is not necessary for running phpMyFAQ, they serve only statistical purposes.

To back up the whole data located on your web server you can run our simple backup script located in the folder /scripts.

back to top


5.13. Configuration

  • Main FAQ configuration Here you can edit the general, the record, spam protection, search and social networks settings of phpMyFAQ. Should you want to enter multiple email addresses in the configuration separate them by a comma (",").
  • System information On this page phpMyFAQ displays some relevant system information like PHP version, database version or session path. Please use this information when report bugs.
  • FAQ Multi-sites You can see a list of all multisite installations, and you're able to add new ones.
  • Stop Words configuration We need stop words for the smart answering feature. If a user is adding a new question to your FAQ the words will be checked against all FAQs in your database but without the stop words. Stop words are words with a very low relevance like the English word "the".
  • Elasticsearch configuration Here you can create and drop the Elasticsearch index, and you can run a full import of all data from your database into the Elasticsearch index. You can also see some Elasticsearch relevant usage data.

back to top


5.14. Multisite Configuration

  • In order to host several distinct installations (with different configs, different templates and most importantly, different database credentials), but only want to update once, you need to follow these steps:

    • Make sure you have the multisite/ directory in your document root and multisite.php in it
    • For every separate installation there needs to be a subdirectory of multisite/ named exactly like the hostname of the separate installation. For example, if you want to use faq.example.org and beta.faq.example.org, it needs to look like this:

      .
      |-- [...]
      |-- config
      |   |-- constants.php
      |   `-- database.php
      `-- multisite
          |-- multisite.php
          `-- beta.faq.example.org
              |-- constants.php
              `-- database.php

back to top


5.15. Template Meta data

If you need to add metadata to your template, you can do this in the template metadata administration. You can define a page type, e.g. "foobar", a content type (Text or HTML) and the content, e.g. <marquee>Foobar</marquee>. After saving the metadata entry, you can use it in your template:

``

back to top


6. Customizing phpMyFAQ 3.x

In phpMyFAQ code and layout are separated. The layout is based on several template files, that you can modify to suit your own needs. The most important files for phpMyFAQ's default layout can be found in the directory assets/themes/default/. All original templates are valid HTML5.

Note: You can change the layout of the admin area using the CSS file admin/css/style.css.

back to top


6.1. HTML Structure

The default layout of phpMyFAQ is saved in the assets/themes/default/templates/index.html file. This is a normal HTML5 file including some variables in double curly brackets like Twig or Handlebars, serving as placeholders for content.

Example:

<span class="useronline"></span>

The template-parser of the FAQ converts the placeholder ** to the actual number of visitors online.

You can change the template as you wish, but you may want to keep the original template in case something goes wrong.

back to top


6.2. Layout

This section needs more documentation.

back to top


6.3. More Templates

You need another template design or more HTML5/CSS3 features? Then write us an email, and we can talk about it.

back to top


7. Customizing phpMyFAQ

phpMyFAQ users have even more customization opportunities. The key feature is the user selectable template sets, there is a templates/default directory where the default layouts get shipped.

back to top


7.1. Creating a custom layout

Follow these steps to create a custom template set:

  • copy the directory assets/themes/default to assets/themes/example
  • adjust template files in assets/themes/example to fit your needs
  • activate "example" within Admin->Config->Main

Note: There is a magic variable ** containing the name of the actual layout available in each template file.

back to top


8. Developer documentation

This part of documentation is for developers who want to contribute to phpMyFAQ.


8.1. phpMyFAQ development

phpMyFAQ is developed using PHP, JavaScript and SCSS. You find further information on our homepage.

back to top


8.2. REST API v2.1

phpMyFAQ offers interfaces to access phpMyFAQ installations with other clients like the iPhone App. phpMyFAQ includes a REST API and offers APIs for various services like fetching the phpMyFAQ version or doing a search against the phpMyFAQ installation.

Open Endpoints

Open endpoints require no Authentication.

General APIs

  • Login: POST /api/v2.1/login

Endpoints that require Authentication

Closed endpoints require a valid API client token to be included in the header of the request. An API client token can be acquired from the admin configuration.

back to top


8.3. DEBUG mode

If you want to see possibe errors or the log of the SQL queries, you can enable the hidden DEBUG mode. To do so, please set the following code in src/Bootstrap.php:

const DEBUG = true;

back to top


9. One more thing

Thank you for using phpMyFAQ! :-)

Author: Thorsten Rinne Co-Authors: Stephan Hochhaus, Markus Gläser

Date: 2022-02-12

© 2001-2022 phpMyFAQ Team

This documentation is licensed under a Creative Commons License.

back to top

Back to the documentation overview