arsd.cgi

Compile versions

If you are using dub, use:

subConfiguration "arsd-official:cgi" "VALUE_HERE"

or to dub.json:

"subConfigurations": {"arsd-official:cgi": "VALUE_HERE"}

to change versions. The possible options for VALUE_HERE are:

• embedded_httpd for the embedded httpd version (built-in web server). This is the default.
• cgi for traditional cgi binaries.
• fastcgi for FastCGI builds.
• scgi for SCGI builds.

With dmd, use:

Compile and run

For CGI, dmd yourfile.d cgi.d then put the executable in your cgi-bin directory.

For FastCGI: dmd yourfile.d cgi.d -version=fastcgi and run it. spawn-fcgi helps on nginx. You can put the file in the directory for Apache. On IIS, run it with a port on the command line.

For SCGI: dmd yourfile.d cgi.d -version=scgi and run the executable, providing a port number on the command line.

For an embedded HTTP server, run dmd yourfile.d cgi.d -version=embedded_httpd and run the generated program. It listens on port 8085 by default. You can change this on the command line with the --port option when running your program.

You can also simulate a request by passing parameters on the command line, like:

./yourprogram GET / name=adr

And it will print the result to stdout.

CGI Setup tips

On Apache, you may do SetHandler cgi-script in your .htaccess file.

Integration tips

cgi.d works well with dom.d for generating html. You may also use web.d for other utilities and automatic api wrapping.

dom.d usage:

import arsd.cgi;
import arsd.dom;

void hello_dom(Cgi cgi) {
	auto document = new Document();

	static import std.file;
	// parse the file in strict mode, requiring it to be well-formed UTF-8 XHTML
	// (You'll appreciate this if you've ever had to deal with a missing </div>
	// or something in a php or erb template before that would randomly mess up
	// the output in your browser. Just check it and throw an exception early!)
	//
	// You could also hard-code a template or load one at compile time with an
	// import expression, but you might appreciate making it a regular file
	// because that means it can be more easily edited by the frontend team and
	// they can see their changes without needing to recompile the program.
	//
	// Note on CTFE: if you do choose to load a static file at compile time,
	// you *can* parse it in CTFE using enum, which will cause it to throw at
	// compile time, which is kinda cool too. Be careful in modifying that document,
	// though, as it will be a static instance. You might want to clone on on demand,
	// or perhaps modify it lazily as you print it out. (Try element.tree, it returns
	// a range of elements which you could send through std.algorithm functions. But
	// since my selector implementation doesn't work on that level yet, you'll find that
	// harder to use. Of course, you could make a static list of matching elements and
	// then use a simple e is e2 predicate... :) )
	document.parseUtf8(std.file.read("your_template.html"), true, true);

	// fill in data using DOM functions, so placing it is in the hands of HTML
	// and it will be properly encoded as text too.
	//
	// Plain html templates can't run server side logic, but I think that's a
	// good thing - it keeps them simple. You may choose to extend the html,
	// but I think it is best to try to stick to standard elements and fill them
	// in with requested data with IDs or class names. A further benefit of
	// this is the designer can also highlight data based on sources in the CSS.
	//
	// However, all of dom.d is available, so you can format your data however
	// you like. You can do partial templates with innerHTML too, or perhaps better,
	// injecting cloned nodes from a partial document.
	//
	// There's a lot of possibilities.
	document["#name"].innerText = cgi.request("name", "default name");

	// send the document to the browser. The second argument to `cgi.write`
	// indicates that this is all the data at once, enabling a few small
	// optimizations.
	cgi.write(document.toString(), true);
}

Concepts: Input: Cgi.get, Cgi.post, Cgi.request, Cgi.files, Cgi.cookies, Cgi.pathInfo, Cgi.requestMethod, and HTTP headers (Cgi.headers, Cgi.userAgent, Cgi.referrer, Cgi.accept, Cgi.authorization, Cgi.lastEventId)

Output: Cgi.write, Cgi.header, Cgi.setResponseStatus, Cgi.setResponseContentType, Cgi.gzipResponse

Cookies: Cgi.setCookie, Cgi.clearCookie, Cgi.cookie, Cgi.cookies

Caching: Cgi.setResponseExpires, Cgi.updateResponseExpires, Cgi.setCache

Redirections: Cgi.setResponseLocation

Other Information: Cgi.remoteAddress, Cgi.https, Cgi.port, Cgi.scriptName, Cgi.requestUri, Cgi.getCurrentCompleteUri, Cgi.onRequestBodyDataReceived

Overriding behavior: Cgi.handleIncomingDataChunk, Cgi.prepareForIncomingDataChunks, Cgi.cleanUpPostDataState

Installing: Apache, IIS, CGI, FastCGI, SCGI, embedded HTTPD (not recommended for production use)

Guide for PHP users

If you are coming from PHP, here's a quick guide to help you get started:

<?php
	$foo = $_POST["foo"];
	$bar = $_GET["bar"];
	$baz = $_COOKIE["baz"];

	$user_ip = $_SERVER["REMOTE_ADDR"];
	$host = $_SERVER["HTTP_HOST"];
	$path = $_SERVER["PATH_INFO"];

	setcookie("baz", "some value");

	echo "hello!";
?>

import arsd.cgi;
void app(Cgi cgi) {
	string foo = cgi.post["foo"];
	string bar = cgi.get["bar"];
	string baz = cgi.cookies["baz"];

	string user_ip = cgi.remoteAddress;
	string host = cgi.host;
	string path = cgi.pathInfo;

	cgi.setCookie("baz", "some value");

	cgi.write("hello!");
}

mixin GenericMain!app

Array elements

In PHP, you can give a form element a name like "something[]", and then $_POST["something"] gives an array. In D, you can use whatever name you want, and access an array of values with the cgi.getArray["name"] and cgi.postArray["name"] members.

Databases

PHP has a lot of stuff in its standard library. cgi.d doesn't include most of these, but the rest of my arsd repository has much of it. For example, to access a MySQL database, download database.d and mysql.d from my github repo, and try this code (assuming, of course, your database is set up):

import arsd.cgi;
import arsd.mysql;

void app(Cgi cgi) {
	auto database = new MySql("localhost", "username", "password", "database_name");
	foreach(row; mysql.query("SELECT count(id) FROM people"))
		cgi.write(row[0] ~ " people in database");
}

mixin GenericMain!app;

Similar modules are available for PostgreSQL, Microsoft SQL Server, and SQLite databases, implementing the same basic interface.