X-Git-Url: http://git.polytechnique.org/?a=blobdiff_plain;f=classes%2Fplmodule.php;h=4f30acd4ff67605c04c55d82f1563c330d607cb2;hb=fa7ffd661d77b24cdb385aca7bdb04c938214061;hp=06e5da837c851f88e133db91bc731ecdd869c782;hpb=ebd515f95f03f8a87f9b846d65e179b39a535222;p=platal.git diff --git a/classes/plmodule.php b/classes/plmodule.php index 06e5da8..4f30acd 100644 --- a/classes/plmodule.php +++ b/classes/plmodule.php @@ -1,6 +1,6 @@ make_hook(...), + * ...); + * @ref make_hook + */ + abstract public function handlers(); /** Register a hook - * @param fun name of the handler (the exact name will be handler_$fun) - * @param auth authentification level of needed to run this handler + * @param fun name of the handler (the exact name will be handler_$fun); the + * handler will be invoked with the PlPage object, and the unmatched path + * components + * @param auth authentification level required to run this handler * @param perms permission required to run this handler * @param type additionnal flags * * Perms syntax is the following: - * perms = rights(,rights)* - * rights = right(:right)* + * perms = rights(,rights)* + * rights = right(:right)* * right is an atomic right permission (like 'admin', 'user', 'groupadmin', 'groupmember'...) * - * If type is set to NO_AUTH, the system will return 403 instead of asking auth data - * this is useful for Ajax handler - * If type is not set to NO_SKIN, the system will consider redirecting the user to https + * If type is set to NO_AUTH, the system will return 403 instead of asking + * auth data; this is useful for Ajax handler. If type is not set to + * NO_SKIN, the system will consider redirecting the user to https. */ public function make_hook($fun, $auth, $perms = 'user', $type = DO_AUTH) { - return array('hook' => array($this, 'handler_'.$fun), - 'auth' => $auth, - 'perms' => $perms, - 'type' => $type); + return new PlStdHook(array($this, 'handler_' . $fun), $auth, $perms, $type); + } + + /** Register an API hook. + * @param fun name of the handler (the exact name will be handler_$fun); the + * handler will be invoked with a PlPage, the authenticated PlUser, the + * JSON-decoded payload (if any), and the unmatched path components + * @param auth authentification level required, when not API-authenticated + * @param perms permission required to run this handler + * @param type additionnal flags (only NO_HTTPS is supported at the moment) + * + * See {@link make_hook} above for details on permissions. + * + * WARNING: It is expected that the API authentication mechanism will not be + * protected against short-term replay of requests (for instance replay of a + * given request within 5-10 seconds). + * + * You are explicitly advised to make any API request idempotent (eg. use + * "DELETE /api/email/foo@example.com" instead of "DELETE /api/email/0" to + * delete the first email in a list). + */ + public function make_api_hook($fun, $auth, $perms = 'user', $type = NO_AUTH) + { + return new PlApiHook(array($this, 'handler_' . $fun), $auth, $perms, $type); + } + + /** Register a token-authentified hook (rss, csv, ical, ...) + * @param fun name of the handler (the exact name will be handler_$fun); the + * handler will be invoked with the PlPage object, the PlUser of the + * request, and the unmatched path components + * @param auth authentification level required, when not token-authentified + * @param perms permission required to run this handler + * @param type additionnal flags + * + * See {@link make_hook} above for details on permissions and additional + * flags. Note that DO_AUTH has no effect here, as the request will always + * be passively identified. + * + * This hook requires that the first two unmatched path components form a + * valid (user, token) pair; if not, a session-based authentification will + * be attempted, in which case $auth will be honored. + * Note that because token-based authentication is weak, it should only be + * used for readonly handlers normally served in AUTH_COOKIE. + */ + public function make_token_hook($fun, $auth, $perms = 'user', $type = NO_HTTPS) + { + return new PlTokenHook(array($this, 'handler_' . $fun), $auth, $perms, $type); + } + + /** Register a hook that points to a wiki page. + */ + public function make_wiki_hook($auth = AUTH_PUBLIC, $perms = 'user', $type = DO_AUTH) + { + return new PlWikiHook($auth, $perms, $type); + } + + /** Include a 'module-specific' file. + * Module specific includes must be in the in the path modules/{modulename}. + */ + public function load($file) + { + require_once $this->modIncludePath . $file; } /* static functions */ + public static function path($modname) + { + global $globals; + if ($modname == 'core') { + $mod_path = $globals->coreroot . '/modules/' . $modname; + } else { + $mod_path = $globals->spoolroot . '/modules/' . $modname; + } + return $mod_path; + } + public static function factory($modname) { - $mod_path = dirname(__FILE__) . '/../modules/' . $modname . '.php'; + $mod_path = self::path($modname); $class = ucfirst($modname) . 'Module'; - require_once $mod_path; - return new $class(); + require_once $mod_path . '.php'; + $module = new $class(); + $module->modIncludePath = $mod_path . '/'; + return $module; } } -// vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8: +// vim:set et sw=4 sts=4 sws=4 foldmethod=marker fenc=utf-8: ?>