Typecho

https://docs.typecho.org/
Admin
Typecho is a lightweight and powerful blogging platform written in PHP, designed for ease of use and...
Tokens:261,950
Snippets:1,517
Trust Score:9.6
Update:5 hours ago
Show doc for...
Tokens:
Raw
### Successful installation output

Source: https://docs.typecho.org/en/guide/getting-started/cli-install/

Example output shown after a successful installation, including the Typecho version, PHP version, and the admin credentials.

```text
Typecho 1.3.0
PHP 8.2.x
Installation successful
Your user name is admin
Your password is your-admin-password
```

--------------------------------

### Start Typecho and view logs

Source: https://docs.typecho.org/en/guide/operations/containers/

Starts the Compose stack and shows the first-start log output, which prints "Installation successful" and the admin account. The admin password appears in plain text in the logs.

```bash
docker compose up -d
docker compose logs typecho   # on first start, prints "Installation successful" and the admin account

```

--------------------------------

### Plugin.php: register route, action, panel and create table

Source: https://docs.typecho.org/en/develop/plugin/routes-actions/

The main plugin class implements PluginInterface. activate() installs the table and registers the route, action, and panel; deactivate() removes them. install() creates the guestbook table with driver-specific SQL for MySQL, PostgreSQL, and SQLite.

```php
<?php

namespace TypechoPlugin\Guestbook;

use Typecho\Db;
use Typecho\Plugin\PluginInterface;
use Typecho\Widget\Helper\Form;
use Utils\Helper;

if (!defined('__TYPECHO_ROOT_DIR__')) {
    exit;
}

/**
 * Guestbook: visitors leave messages on the front-end /guestbook/ page; view and delete them under "Manage → Messages" in the admin panel
 *
 * @package Guestbook
 * @author Your Name
 * @version 1.0.0
 * @since 1.3.0
 */
class Plugin implements PluginInterface
{
    public static function activate()
    {
        self::install();

        Helper::addRoute('guestbook', '/guestbook/', Action::class, 'render', 'index');
        Helper::addAction('guestbook', Action::class);
        Helper::addPanel(3, 'Guestbook/panel.php', _t('Messages'), _t('Manage messages'), 'administrator');
    }

    public static function deactivate()
    {
        Helper::removeRoute('guestbook');
        Helper::removeAction('guestbook');
        Helper::removePanel(3, 'Guestbook/panel.php');
    }

    public static function config(Form $form)
    {
    }

    public static function personalConfig(Form $form)
    {
    }

    /**
     * Creates the table, with one version for each of the three databases
     */
    public static function install()
    {
        $db = Db::get();
        $table = $db->getPrefix() . 'guestbook';

        switch ($db->getAdapter()->getDriver()) {
            case 'mysql':
                $db->query("CREATE TABLE IF NOT EXISTS `{$table}` (
                    `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
                    `author` varchar(150) DEFAULT NULL,
                    `text` text,
                    `ip` varchar(64) DEFAULT NULL,
                    `created` int(10) unsigned DEFAULT '0',
                    PRIMARY KEY (`id`),
                    KEY `created` (`created`)
                ) DEFAULT CHARSET=utf8mb4", Db::WRITE);
                break;
            case 'pgsql':
                $db->query("CREATE TABLE IF NOT EXISTS \"{$table}\" (
                    \"id\" SERIAL PRIMARY KEY,
                    \"author\" VARCHAR(150) NULL DEFAULT NULL,
                    \"text\" TEXT NULL DEFAULT NULL,
                    \"ip\" VARCHAR(64) NULL DEFAULT NULL,
                    \"created\" INT NULL DEFAULT '0'
                )", Db::WRITE);
                $db->query("CREATE INDEX IF NOT EXISTS \"{$table}_created\" ON \"{$table}\" (\"created\")", Db::WRITE);
                break;
            case 'sqlite':
                $db->query("CREATE TABLE IF NOT EXISTS \"{$table}\" (
                    \"id\" INTEGER NOT NULL PRIMARY KEY,
                    \"author\" varchar(150) DEFAULT NULL,
                    \"text\" text,
                    \"ip\" varchar(64) DEFAULT NULL,
                    \"created\" int(10) DEFAULT '0'
                )", Db::WRITE);
                $db->query("CREATE INDEX IF NOT EXISTS \"{$table}_created\" ON \"{$table}\" (\"created\")", Db::WRITE);
                break;
        }
    }
}
```

--------------------------------

### Check installation status with exit code

Source: https://docs.typecho.org/en/guide/getting-started/cli-install/

Runs the Typecho installer and prints a fallback message if installation fails or the site is already installed. Both failure cases exit with code 1, so check the output to distinguish them.

```bash
php install.php || echo "Installation failed, or the site is already installed"
```

--------------------------------

### Run Typecho installer from CLI

Source: https://docs.typecho.org/en/guide/getting-started/cli-install/

Run the Typecho installer directly from the command line. When executed under the CLI, it skips the web interface and reads configuration from environment variables.

```bash
php install.php
```

--------------------------------

### SQLite installation with environment variables

Source: https://docs.typecho.org/en/guide/getting-started/cli-install/

Install Typecho with SQLite using the minimum configuration. The database file is placed outside the site directory and the directory must be created beforehand. Run as the web server account (e.g., www-data) to ensure proper file ownership.

```bash
cd /srv/www/typecho
sudo -u www-data env \
  TYPECHO_SITE_URL=https://blog.example.com \
  TYPECHO_DB_ADAPTER=Pdo_SQLite \
  TYPECHO_DB_FILE=/srv/data/typecho/site.db \
  php install.php
```

--------------------------------

### Query Building Example

Source: https://docs.typecho.org/en/develop/plugin/database/

Example of building a query with a join to fetch published posts in a category, using the chainable methods.

```APIDOC
## Query Building Example

### Description
Demonstrates how to use the chainable methods of `Typecho\Db\Query` to fetch published posts in a category using a join.

### Code
```php
$db = \Typecho\Db::get();

$posts = $db->fetchAll($db->select('table.contents.cid', 'table.contents.title')
    ->from('table.contents')
    ->join('table.relationships', 'table.contents.cid = table.relationships.cid')
    ->where('table.relationships.mid = ?', 1)
    ->where('table.contents.type = ?', 'post')
    ->where('table.contents.status = ?', 'publish')
    ->order('table.contents.created', \Typecho\Db::SORT_DESC));
```
```

--------------------------------

### MySQL installation with environment variables

Source: https://docs.typecho.org/en/guide/getting-started/cli-install/

Install Typecho with MySQL using environment variables. The database must be created beforehand; otherwise, an error is shown. Run as the web server account to avoid file ownership issues.

```bash
cd /srv/www/typecho
export TYPECHO_SITE_URL=https://blog.example.com
export TYPECHO_DB_ADAPTER=Pdo_Mysql
export TYPECHO_DB_HOST=127.0.0.1
export TYPECHO_DB_USER=typecho
export TYPECHO_DB_PASSWORD='your-db-password'
export TYPECHO_DB_DATABASE=typecho
export TYPECHO_USER_NAME=admin
export TYPECHO_USER_PASSWORD='your-admin-password'
export TYPECHO_USER_MAIL=admin@example.com
php install.php
```

--------------------------------

### Build the documentation site locally

Source: https://docs.typecho.org/en/develop/contributing/docs/

Clone the repository, install dependencies with pnpm, and run the development server or build the site. The build must pass without warnings.

```bash
git clone https://github.com/typecho/docs.git
cd docs
pnpm install

pnpm start                  # preview the Chinese site locally; reloads on changes
pnpm start --locale en      # preview the English site locally
pnpm build                  # build both the Chinese and English versions into build/
```

--------------------------------

### Using get() with existence check

Source: https://docs.typecho.org/en/develop/core/request-response/

Example of using get() with the third argument to check if a parameter exists. If the parameter is not submitted, $exists is false.

```php
$page = $this->request->get('page', 1, $exists);
if (!$exists) {
    // page was not submitted
}
```

--------------------------------

### filter() with get() for typed reads

Source: https://docs.typecho.org/en/develop/core/request-response/

Example of using filter() to apply filters once before reading. Filters are cleared after the read. Shows int, slug, and trim+html filters.

```php
$cid  = $this->request->filter('int')->get('cid');            // to an integer
$slug = $this->request->filter('slug')->get('slug');          // to a slug
$text = $this->request->filter('trim', 'html')->get('text');  // trim, then htmlspecialchars
```

--------------------------------

### Complete Greeting plugin example

Source: https://docs.typecho.org/en/develop/plugin/settings/

Full plugin implementation demonstrating settings configuration, validation, custom saving, personal settings, and front-end/admin hooks. Includes activation and deactivation methods.

```php
<?php

namespace TypechoPlugin\Greeting;

use Typecho\Plugin\PluginInterface;
use Typecho\Widget\Helper\Form;
use Typecho\Widget\Helper\Form\Element\Radio;
use Typecho\Widget\Helper\Form\Element\Text;
use Utils\Helper;
use Widget\Options;

if (!defined('__TYPECHO_ROOT_DIR__')) {
    exit;
}

/**
 * Shows a greeting in the admin navigation bar and the front-end footer
 *
 * @package Greeting
 * @author Your Name
 * @version 1.1.0
 * @since 1.3.0
 * @link https://example.com
 */
class Plugin implements PluginInterface
{
    public static function activate()
    {
        \Typecho\Plugin::factory('admin/menu.php')->navBar = __CLASS__ . '::navBar';
        \Typecho\Plugin::factory('Widget\Archive')->footer = __CLASS__ . '::footer';
    }

    public static function deactivate()
    {
    }

    public static function config(Form $form)
    {
        $word = new Text('word', null, 'Hello', _t('Greeting'));
        $word->addRule('required', _t('The greeting cannot be empty'));
        $form->addInput($word);

        $position = new Radio('position', [
            'navBar' => _t('Admin navigation bar'),
            'footer' => _t('Front-end footer'),
            'both'   => _t('Both'),
        ], 'both', _t('Display location'));
        $form->addInput($position);
    }

    public static function configCheck(array $settings)
    {
        if (mb_strlen($settings['word']) > 20) {
            return _t('Settings saved. The greeting is long and may be cut off in the admin navigation bar');
        }
    }

    public static function configHandle(array $settings, bool $isInit)
    {
        $settings['word'] = trim($settings['word']);
        Helper::configPlugin('Greeting', $settings);
    }

    public static function personalConfig(Form $form)
    {
        $nickname = new Text('nickname', null, '', _t('How the navigation bar addresses you'));
        $form->addInput($nickname);

        return 'contributor';
    }

    public static function navBar()
    {
        $config = Options::alloc()->plugin('Greeting');
        if ($config->position == 'footer') {
            return;
        }

        $text = $config->word;
        try {
            $nickname = Options::alloc()->personalPlugin('Greeting')->nickname;
        } catch (\Typecho\Plugin\Exception $e) {
            $nickname = null;
        }
        if (!empty($nickname)) {
            $text .= ', ' . $nickname;
        }

        echo '<span class="message success">' . htmlspecialchars($text) . '</span>';
    }

    public static function footer()
    {
        $config = Options::alloc()->plugin('Greeting');
        if ($config->position != 'navBar') {
            echo '<p class="greeting">' . htmlspecialchars($config->word) . '</p>';
        }
    }
}
```

--------------------------------

### Remove installer after installation

Source: https://docs.typecho.org/en/guide/operations/security/

Run these commands in the Typecho root directory to delete install.php and the install/ directory, which are no longer needed after installation.

```bash
cd /srv/www/typecho
rm -rf install.php install/
```

--------------------------------

### Directory structure for starter theme

Source: https://docs.typecho.org/en/develop/theme/quick-start/

Shows the required file layout for the 'starter' theme under usr/themes/. Only index.php is mandatory; other templates fall back to index.php if missing.

```text
usr/themes/starter/
├── index.php      required: theme info + post list
├── header.php     header
├── footer.php     footer
├── post.php       post page
├── page.php       page
├── comments.php   comment list and comment form
├── 404.php        page not found
├── functions.php  callbacks such as theme settings
└── style.css      styles
```

--------------------------------

### Clone and run Typecho development copy with SQLite and built-in server

Source: https://docs.typecho.org/en/develop/core/build/

Sets up a local Typecho development environment. Requires PHP 7.4+ and a supported database (SQLite recommended). Clones the repository, installs via command line with environment variables, then runs PHP's built-in server. The server serves existing files directly and passes non-existent paths to index.php, so both front-end URLs and /action/* work.

```bash
git clone https://github.com/typecho/typecho.git
cd typecho

# Command-line installation with SQLite
TYPECHO_SITE_URL=http://127.0.0.1:8000 \
TYPECHO_DB_ADAPTER=Pdo_SQLite \
TYPECHO_DB_FILE=$PWD/usr/dev.db \
TYPECHO_USER_NAME=admin \
TYPECHO_USER_PASSWORD=admin123456 \
php install.php

# Run with PHP's built-in server
php -S 127.0.0.1:8000
```

--------------------------------

### Rerun Typecho CLI installer with TYPECHO_DB_NEXT=keep for MySQL

Source: https://docs.typecho.org/en/guide/getting-started/cli-install/

Use this command to retry the Typecho CLI installation after a partial failure. It sets all required environment variables, including the missing TYPECHO_SITE_URL, and adds TYPECHO_DB_NEXT=keep to keep existing tables. The installer validates variables first; for MySQL, missing TYPECHO_DB_USER or TYPECHO_DB_DATABASE causes an error. If config.inc.php already exists, the installer uses its database connection after validation.

```bash
TYPECHO_SITE_URL=https://blog.example.com \
TYPECHO_DB_ADAPTER=Pdo_Mysql \
TYPECHO_DB_HOST=127.0.0.1 \
TYPECHO_DB_USER=typecho \
TYPECHO_DB_PASSWORD='your-db-password' \
TYPECHO_DB_DATABASE=typecho \
TYPECHO_DB_NEXT=keep \
php install.php
```

--------------------------------

### Directory layout example

Source: https://docs.typecho.org/en/develop/plugin/structure/

Shows the file structure of a directory-based plugin, with the entry file Plugin.php and other classes autoloaded by namespace.

```text
usr/plugins/Guestbook/
├── Plugin.php        \TypechoPlugin\Guestbook\Plugin
├── Action.php        \TypechoPlugin\Guestbook\Action
├── Storage/
│   └── Message.php   \TypechoPlugin\Guestbook\Storage\Message
├── panel.php         admin panel (a plain PHP file; see "Routes, Actions and Admin Panels")
└── lang/             language files
```

--------------------------------

### Example problem description

Source: https://docs.typecho.org/en/guide/help/getting-help/

A sample problem description following the recommended structure, including description, steps to reproduce, expected result, platform details, and already tried actions.

```text
Description: after upgrading to 1.3.0, clicking "Complete upgrade" keeps the page loading, and it ends with a 504.

Steps to reproduce:
1. Replace admin/ var/ install/ index.php install.php from 1.2.1
2. Log in to the admin panel as an administrator; you are taken to the upgrade page
3. Click "Complete upgrade"; the page keeps loading for about 60 seconds, then returns 504

Expected result: "The upgrade has been completed" is shown

Platform:
- OS version: Debian 12
- Apache/Nginx version: nginx 1.22.1
- Database version: MariaDB 10.11.6
- PHP version: PHP 8.2.20
- Typecho version: 1.2.1 → 1.3.0
- Browser version: Firefox 131

Already tried: disabled all plugins and retried, same result. The site has about 800 attachments.
```

--------------------------------

### PHP define() example for custom attachment storage constants

Source: https://docs.typecho.org/en/guide/operations/uploads-storage/

Example of defining the three constants in config.inc.php to store attachments in /data/typecho/files and serve them from a CDN.

```php
define('__TYPECHO_UPLOAD_ROOT_DIR__', '/data/typecho');
define('__TYPECHO_UPLOAD_DIR__', '/files');
define('__TYPECHO_UPLOAD_URL__', 'https://cdn.example.com');
```

--------------------------------

### style.css for starter theme

Source: https://docs.typecho.org/en/develop/theme/quick-start/

A minimal stylesheet for the starter theme. Sets a centered layout with a max-width of 720px, flexbox for header/footer, and styling for meta, tags, and post navigation.

```css
body { max-width: 720px; margin: 0 auto; padding: 0 16px; font-family: sans-serif; line-height: 1.7; }
.site-header, .site-footer { display: flex; gap: 1em; align-items: center; flex-wrap: wrap; padding: 1em 0; }
.site-title { font-weight: bold; }
.meta, .tags { color: #888; font-size: .9em; }
.post-nav { display: flex; justify-content: space-between; margin: 2em 0; }
```

--------------------------------

### Allowed HTML tags example

Source: https://docs.typecho.org/en/guide/settings/discussion/

Example of allowed HTML tags and attributes for the 'Allowed HTML tags and attributes' setting. Only the listed attributes are kept for each tag.

```html
<a href=""> <img src=""> <blockquote>
```

--------------------------------

### Install dependencies with npm ci

Source: https://docs.typecho.org/en/develop/core/build/

Run this in the tools directory to install dependencies from package-lock.json. Requires Node.js 18 because node-sass compiles a native module that fails on newer versions.

```bash
cd tools
npm ci          # install from package-lock.json
```

--------------------------------

### options(): Options

Source: https://docs.typecho.org/en/develop/reference/helper/

Returns \Widget\Options::alloc(); see $this->options.

```APIDOC
## options(): Options

### Description
Returns \Widget\Options::alloc(); see $this->options.

### Method
options

### Returns
- **Options** - The Options widget instance.
```

--------------------------------

### get() method signature

Source: https://docs.typecho.org/en/develop/core/request-response/

Signature of the get() method. It looks for the first value in request parameters, $_GET, then $_POST. Empty strings are treated as non-existent, and array/string mismatches return the default.

```php
public function get(string $key, $default = null, ?bool &$exists = true)
```

--------------------------------

### Upgrade method example in var/Utils/Upgrade.php

Source: https://docs.typecho.org/en/develop/core/upgrade-scripts/

Shows the structure of upgrade methods in var/Utils/Upgrade.php. Methods must be public static, named v<version> (e.g., v1_3_0, v1_3_1), and declared in ascending version order. The v1_3_1 method demonstrates a database update using Db\Query and an optional return message shown to the administrator.

```php
namespace Utils;

use Typecho\Db;
use Widget\Options;

class Upgrade
{
    public static function v1_3_0(Db $db, Options $options)
    {
        // ……
    }

    /**
     * Migration for 1.3.1
     */
    public static function v1_3_1(Db $db, Options $options)
    {
        $db->query($db->update('table.options')
            ->rows(['value' => '0'])
            ->where('name = ? AND user = 0', 'someOption'));

        // Optional: return a message shown to the administrator after the upgrade
        return _t('someOption has been reset');
    }
}
```

--------------------------------

### index.php - minimal theme template

Source: https://docs.typecho.org/en/develop/theme/quick-start/

The main template file for the starter theme. It includes the theme header comment, security check, includes header/footer, outputs post lists with archive titles, pagination, and handles empty results. The @package name appears in the admin panel.

```php
<?php
/**
 * A minimal example theme
 *
 * @package Starter
 * @author Your Name
 * @version 1.0.0
 * @link https://example.com
 */
if (!defined('__TYPECHO_ROOT_DIR__')) exit;
$this->need('header.php');
?>
<main>
    <?php if (!$this->is('index')): ?>
        <h1><?php $this->archiveTitle([
            'category' => _t('Posts in category %s'),
            'search'   => _t('Posts containing %s'),
            'tag'      => _t('Posts tagged %s'),
            'author'   => _t('Posts by %s'),
        ], '', ''); ?></h1>
    <?php endif; ?>

    <?php if ($this->have()): ?>
        <?php while ($this->next()): ?>
            <article>
                <h2><a href="<?php $this->permalink(); ?>"><?php $this->title(); ?></a></h2>
                <p class="meta">
                    <?php $this->date(); ?> ·
                    <?php $this->category(', '); ?> ·
                    <a href="<?php $this->permalink(); ?>#comments"><?php $this->commentsNum(_t('No comments yet'), _t('1 comment'), _t('%d comments')); ?></a>
                </p>
                <?php $this->content(_t('Read more')); ?>
            </article>
        <?php endwhile; ?>
    <?php else: ?>
        <p><?php _e('Nothing found'); ?></p>
    <?php endif; ?>

    <?php $this->pageNav('&laquo; ' . _t('Previous'), _t('Next') . ' &raquo;'); ?>
</main>
<?php $this->need('footer.php'); ?>
```

--------------------------------

### Get commit hash of Chinese source file

Source: https://docs.typecho.org/en/develop/contributing/docs/

Run this command to get the hash of the last commit for a Chinese source file, used in the translation workflow to track the source version.

```bash
git log -1 --format=%H -- docs/develop/core/router.md
```

--------------------------------

### Example debug output

Source: https://docs.typecho.org/en/guide/operations/debugging/

Example of the output shown when debug mode is enabled and an uncaught exception occurs. It displays the error message and full stack trace, exposing server paths and class names.

```text
SQLSTATE[HY000] [14] unable to open database file
Typecho\Db\Adapter\ConnectionException: SQLSTATE[HY000] [14] unable to open database file in /srv/www/typecho/var/Typecho/Db/Adapter/Pdo.php:62
Stack trace:
#0 /srv/www/typecho/var/Typecho/Db.php(218): Typecho\Db\Adapter\Pdo->connect(Object(Typecho\Config))
...
```

--------------------------------

### Configure read/write splitting with addServer()

Source: https://docs.typecho.org/en/guide/operations/config-file/

Shows how to set up a primary database connection for writes and a read-only replica for reads using Typecho\Db::addServer(). The WRITE and READ constants specify the server roles.

```php
$db = new \Typecho\Db('Pdo_Mysql', 'typecho_');
$db->addServer([/* primary connection parameters */], \Typecho\Db::WRITE);
$db->addServer([/* read-only replica connection parameters */], \Typecho\Db::READ);
\Typecho\Db::set($db);
```
Tokens:
Raw