NacoWiki PHP API

NacoWikiApp
in package

NWikiApp

Main Application class

Properties

$cfg : array<string|int, mixed>: Contains running app configuration *
$context : array<string|int, mixed>: Current user/session context
$ctxvars : array<string|int, mixed>: Defined context variables
$http_host : string|null: HTTP request host
$https : bool: TRUE if using https
$meta : array<string|int, mixed>: Current document meta-data.
$opts : array<string|int, mixed>: Local customizations
$page : string: Current document
$props : array<string|int, mixed>: Current document properties
$remote_addr : string|null: HTTP client's remote address
$remote_user : string|null: HTTP client's remote user (if any)
$scheme : string|null: HTTP context, should be set to http or https, otherwise is NULL
$view : string: Default view class

Methods

__construct() : mixed: Create a new NanoWiki application instance
asset() : string: Returns a URL to an static file asset
assetQS() : string: Returns a URL to an static file asset with timestamp
cli() : void: Main dispatch point for CLI sub-commands
declareContext() : void: Declare a context variable.
errMsg() : void: Show a HTML error message and dies.
filePath() : string: Convert URL to an actual file path
getUser() : string|null: Get current user
initContext() : void: Initialize user context
isReadable() : bool|null: Current document is readable
isWritable() : bool|null: Current document is writable
loadOpts() : void: Load option files
mkUrl() : string: Create a URL to the given resource.
navInfoBox() : mixed: Add InfoBox items
navTools() : mixed: Add nav Tools
run() : void: Main application entry point method

$cfg

Contains running app configuration *


    public
        array<string|int, mixed>
    $cfg
     = [
    ##-- configuration#NacoWiki configuration
    ##
    ## - umask (int) - Optional umask
    'umask' => \NULL,
    ## - proxy-ips (array|string) : list of IP addresses of trusted reverse proxies
    ##   Either as an array of strings, or as string with comma separated IP addresses.
    'proxy-ips' => \NULL,
    ## - no_cache (bool) : defaults to false.  If set to true, enables
    ##   sending of headers that disable browser caches.
    'no_cache' => \false,
    ## - plugins_path (array|string) : list of directories where to look for plugins. \
    ##   Defaults to `APP_DIR/plugins`. \
    ##   It can be specified as an array of strings, or as single array with
    ##   paths separated by PHP's PATH_SEPARATOR `:` under Linux, `;` under Windows.
    'plugins_path' => \NULL,
    ## - base_url (string) - Base Application URL \
    ##   Normally defaults to the HTTP SCRIPT_NAME value.  However, it can
    ##   be changed for placing after a reverse proxy which changes the path.
    'base_url' => \NULL,
    ## - static_url (string) - URL Path to static resources \
    ##   Normally defaults to the dirname of HTTP SCRIPT_NAME.  However, it can
    ##   be changed for placing after a reverse proxy which changes the path. \
    ##   It has to be a HTTP path that can reach the static resources.
    'static_url' => \NULL,
    ## - static_path (string) - File Path to static resources \
    ##   Path in the filesystem to reach the actual static resources.  Defaults
    ##   to `APP_DIR/assets`.
    'static_path' => \NULL,
    ## - file_store (string) -  Location where data files are stored \
    ##   Defaults to `CWD/files`.  These files do *NOT* need to be served
    ##   by the web server, so that the PHP script can control all access
    ##   to them.
    'file_store' => \NULL,
    ## - read_only (bool|string) - if true, makes the wiki read-only.  Defaults to false. \
    ##   if set to `not-auth`, it will make it read-only until the user
    ##   authenticates.
    'read_only' => \false,
    ## - unix_eol (bool) - force all input files to be converted from CRLF to UNIX style
    ##   LF for the EOL marker.  Defaults to true.  Set to false if you want
    ##   to keep CRLF as EOL markers.
    'unix_eol' => \true,
    ## - default_doc (string) - the default document for browsing into folders. \
    ##   defaults to `index.md`.
    'default_doc' => 'index.md',
    ## - plugins (array) - Plugin configuration \
    ##   Plugins can read its own configuration from this array. By
    ##   convention, they should read only from the keys matching the
    ##   plugin name.  In addition, you can enable or disable
    ##   plugins with the keys:
    ##   - enabled (string|array) - list of plugins to enable either as a
    ##     string with comma separated name of plugins or as an array with
    ##     plugin names.
    ##   - disabled (string|array) - list of plugins to disable either as a
    ##     string with comma separated name of plugins or as an array with
    ##     plugin names.
    ##   By default all found plugins will be enabled.
    'plugins' => [],
    // Plugin configuration
    ## - cookie_id (string) - used to keep cookies unique
    'cookie_id' => \NULL,
    ## - cookie_age (int) - seconds to keep the cookies alive. \
    ##   Defaults to 30 days.
    'cookie_age' => 86400 * 30,
    ## - ext_url (string) - URL used in the logo link.  Defaults to
    ##   the current http host home page.
    'ext_url' => '/',
    ## - title (string) - Window title bar
    'title' => 'NacoWiki',
    ## - copyright (string) - copyright text show in the footer
    'copyright' => 'nobody@nowhere',
    ## - theme (string) - Overall nacowiki theme
    'theme' => 'nacowiki',
    ## - theme-highlight-js (string) - theme to be used for syntax highlighting
    'theme-highlight-js' => \NULL,
    // highlight.js theme
    ## - theme-codemirror (string) - CodeMirror theme
    'theme-codemirror' => \NULL,
]

$context

Current user/session context


    public
        array<string|int, mixed>
    $context
     = []

$ctxvars

Defined context variables


    public
        array<string|int, mixed>
    $ctxvars
     = []

$http_host

HTTP request host


    public
        string|null
    $http_host
     = \NULL

$https

TRUE if using https


    public
        bool
    $https
     = \false

$meta

Current document meta-data.


    public
        array<string|int, mixed>
    $meta
     = []

$wiki->meta is loaded from the front matter in the stored article and can be modified by users with write access. This is unlike $wiki->props that are managed by the system (either via core or by plugin).

$opts

Local customizations


    public
        array<string|int, mixed>
    $opts
     = []

$page

Current document


    public
        string
    $page
     = ''

$props

Current document properties


    public
        array<string|int, mixed>
    $props
     = []

$wiki->props is loaded and managed automatically by the system (either via core or by plugin). This is unlike $wiki->meta that are loaded from the editable file and can be modified arbitraily by users with write access.

$remote_addr

HTTP client's remote address


    public
        string|null
    $remote_addr
     = \NULL

$remote_user

HTTP client's remote user (if any)


    public
        string|null
    $remote_user
     = \NULL

$scheme

HTTP context, should be set to http or https, otherwise is NULL


    public
        string|null
    $scheme
     = \NULL

$view

Default view class


    public
        string
    $view
     = 'default'

__construct()

Create a new NanoWiki application instance


    public
                    __construct([array<string|int, mixed> $config = [] ]) : mixed

The given $config contains keys to override the default configuration.

Parameters

$config : array<string|int, mixed> = []: NanoWiki configuration

asset()

Returns a URL to an static file asset


    public
                    asset(string $id) : string

This returns a string to a static file asset. The URL is supposed to be used so that the Web server can send the asset directly to the user (by-passing PHP).

Parameters

$id : string: asset identifier

Return values

string —

URL to the asset

assetQS()

Returns a URL to an static file asset with timestamp


    public
                    assetQS(string $id) : string

This returns a string to a static file asset. The URL is supposed to be used so that the Web server can send the asset directly to the user (by-passing PHP).

This works just like the asset method, with the difference that the URL also has a query string of the form of '?t=number`. The number is the mtime of the asset as returned by PHP's filemtime.

The purpose is so that the URL send to the browser is different every time the file changes. This is useful for Web browsers that tend to aggresively cache JavaScript code.

Parameters

$id : string: asset identifier

Return values

string —

URL to the asset

cli()

Main dispatch point for CLI sub-commands


    public
                    cli(array<string|int, mixed> $argv) : void

It will arrange for the given sub-command to be executed. This is done by firing the event cli:SUBCOMMAND. Where SUBCOMMAND is the sub-command specified in the command line.

The current instance will also get the following properties defined:

$this->script : $argv[0], usually the script name
$this->cwd : Working directory form the command was invoked
$this->script_dir : Directory of the script
$this->clicmd : sub command being executed.

Parameters

$argv : array<string|int, mixed>

declareContext()

Declare a context variable.


    public
                    declareContext(string $key[, mixed $default = NULL ]) : void

Declare context variables that persist in an user session. This is implemented using Cookies.

Plugins should hook into the run-init event and declare context variables there. Value of these variables can be read from the $wiki->context[$key]

Parameters

$key : string: variable name to declare
$default : mixed = NULL: default value.

errMsg()

Show a HTML error message and dies.


    public
                    errMsg(string $tag, string $msg[, int $flags = EM_NONE ]) : void

Shows an HTML error message and exits. You can pass optional flags:

EM_NONE: default, no special processing
EM_PHPERR: Display the last PHP Error using php's error_get_last

Parameters

$tag : string: a tag used to identify the error.
$msg : string: Error message to display.
$flags : int = EM_NONE: Flags with options. Defaults to EM_NONE

filePath()

Convert URL to an actual file path


    public
                    filePath([string|null $url = NULL ]) : string

Parameters

$url : string|null = NULL: URL to translate, If not given, it would use $this->page

Return values

string —

actual file path to $url in the filesystem.

getUser()

Get current user


    public
                    getUser() : string|null

Return values

string|null

initContext()

Initialize user context


    public
                    initContext() : void

It would initialize the class context property from the http cookies. Also it would allow the user to change the context through $_GET variables. Specifically, you can use:

...url...?ctx_VARNAME=value

to set the context variable VARNAME to the given value.

Similarly, you can use:

...url...?noctx_VARNAME=null

To set VARNAME to its default value.

Example:

ctx_debug=true

This enables the debug context variable.

isReadable()

Current document is readable


    public
                    isReadable([string|null $url = NULL ]) : bool|null

Parameters

$url : string|null = NULL: URL to translate, If not given, it would use $this->page

Return values

bool|null —

returns true if allowed, false if not. NULL if user is not authenticated.

isWritable()

Current document is writable


    public
                    isWritable([string|null $url = NULL ]) : bool|null

This is the entry point to check if remote user has access to this file. At the moment, the minimum functionality is to check if there is OS write access to the file.

Parameters

$url : string|null = NULL: URL to translate, If not given, it would use $this->page

Return values

bool|null —

returns true if allowed, false if not. NULL if user is not authenticated.

loadOpts()

Load option files


    public
                    loadOpts(string $url) : void

Parameters

$url : string: path of option files to read

mkUrl()

Create a URL to the given resource.


    public
                    mkUrl(string $base, mixed ...$params) : string

Given the $base and $params, it would compute a URL to the given resource.

$params is an array of strings or arrays. If a string is passed in $params, it will simply append it to the URL as another path component. If an array is passed, it will use it to create a HTTP query string using PHP http_build_query.

Parameters

$base : string: URL to compute
$params : mixed: varargs with additional arguments

Return values

string —

URL to the given resource.

navInfoBox()

Add InfoBox items


    public
                    navInfoBox(array<string|int, mixed> &$info) : mixed

Used to add items to the infobox table of the top nav bar.

Parameters

$info : array<string|int, mixed>: array to receive the new items.

navTools()

Add nav Tools


    public
                    navTools(string $mode) : mixed

Used to add components to navigation HTML from Plugins.

Parameters

$mode : string: string with current mode.

run()

Main application entry point method


    public
                    run([array<string|int, mixed>|null $argv = NULL ]) : void

Parameters

$argv : array<string|int, mixed>|null = NULL: Normally NULL. Contains command line arguments if run from CLI

NacoWikiApp in package NWikiApp

Table of Contents

Properties

Methods

Properties

$cfg

$context

$ctxvars

$http_host

$https

$meta

$opts

$page

$props

$remote_addr

$remote_user

$scheme

$view

Methods

__construct()

Parameters

asset()

Parameters

Return values

assetQS()

Parameters

Return values

cli()

Parameters

Tags

declareContext()

Parameters

errMsg()

Parameters

Tags

filePath()

Parameters

Return values

getUser()

Tags

Return values

initContext()

Tags

isReadable()

Parameters

Tags

Return values

isWritable()

Parameters

Tags

Return values

loadOpts()

Parameters

mkUrl()

Parameters

Return values

navInfoBox()

Parameters

navTools()

Parameters

run()

Parameters

NacoWikiApp
in package

NWikiApp